Readme.txt - Harness2.cfm 1.02 by jeff@grokfusebox.com
10 Jan 2003
====================================================================
Harness2 is a tool that constructs test harnesses for ColdFusion applications developed using the Fusebox 3 methodology.  It operates on the assumption that files incorporate documentation headers using the Fusedoc 2.0 standard developed by Hal Helms and the Fusebox community.  
For information on Fusebox, visit http://www.fusebox.org
For information on Fusedoc, visit http://www.halhelms.com

When in the production environment, fusebox files perform their work and return control to the fusebox file.  Test harnesses are a way to provide the variables expected by a fuse and observe the output of the fuse as a unit.  This allows you to unit test your code before placing it into a full test environment, making final debugging much less painful.

In order to facilitate unit testing, we make use of a variable called "self" to tell the fuse the location to call next.  In production, of course, this variable contains the value "index.cfm", the fusebox file.  Test harnesses assign a different value to the variable, allowing the use of another process to dump variables, or whatever you wish to use in monitoring output from the fuse being unit tested.

=================
Prerequisites
=================
Harness2 should run without problems in any version of ColdFusion from 4.5 on.
The SOXML custom tag is required; if you don't have it installed go to http://www.siteobjects.com
(A CFMX-only version may be next on the drawing board, time permitting.)

=================
Using Harness2
=================
What does Harness2 do?  It recurses the directory tree, starting in the specified directory, and creates a test harness for any file with a Fusebox prefix of "dsp" or "act".  If the file has a Fusedoc header in it, Harness2 will read the Fusedoc and do its best to create the required variables in the file's test harness.  If the file doesn't have a properly constructed Fusedoc header, Harness2 will throw an error and inform you of the name of the file where the offending Fusedoc lives.  (Mind those closing slashes!)

Before you run Harness2, take a look at the harness.ini file.  This configuration file tells Harness2 how you'd like the global initialization lines in your test harnesses to look.  You may modify the lines as you wish; the LineCount key tells Harness2 how many lines to use.  For example, if you design keys for Line1 through Line17, but you set LineCount equal to 5, Harness2 will only use lines 1 through 5.

Once you have a harness.ini that meets with your approval, you're ready to run Harness2.  It's called as a custom tag; you can place Harness2.cfm and harness.ini in your Custom Tags directory or in the directory at the top of the application for which you're building harnesses.  You can also create any number of ini files and tell Harness2 which one to use with the "ini" attribute.

The template "har2Call.cfm" shows a sample use of Harness2.  The attributes available are:

 thisDir: directory from which to start process.  
          Defaults to current directory.
          
 verbose: whether to display process information.  
          Defaults to Yes.
          
prefixes: a list of file prefixes to process.  
          Defaults to "dsp,act"
          You may use "*" to cause Harness2 to ignore file prefixes and create a test harness 
          for all files found.  Be careful if you use the * value--be sure you really want 
          Harness2 to process ALL the files in the directory structure.
          
     ini: file containing global harness settings.  
          Defaults to "harness.ini" in the directory where Harness2.cfm is 
          located.

Once you've run Harness2, you'll have a test harness for each file that passes the prefixes filter.  Test harnesses add a prefix of "tst_" to the file name.

Note that Harness2, because of its much more thorough nature compared with the original Harness, may take a bit of time to process through a complete application.  Patience is the watchword--after all, you could be coding all those test harnesses by hand, right?  Have a cup o'joe and watch the show.

Happy Testing!
- Jeff Peters

=================
Version History
=================
1.04 - 2003-01-31:
- Contributions by Kevin Roche (kevin@objectiveinternet.com)
- Limits processing to start mode.
- Adds comments to test harnesses.
- Adds include section from harness2.ini at the end of the harness file (ShowResults section of harness2.ini)
- Adds UserData section to harness2.ini.
1.03 - 2003-01-17: Update prevents styles from being written more than once. 
1.02 - 2003-01-10: First public release that makes the author happy. ;)  This code is functional, though quite bloated.  Streamlining may (or may not) follow as time permits.
1.01 - 2002-08-02: First public release; pulled due to fatal bug in processing nested complex Fusedocs.
1.00 - 2001-10-23: Initial version; not released to public.
